Skip to content

[Node.js] Align Public APIs across SDKs#221

Merged
fpfp100 merged 17 commits intomainfrom
users/pefan/syncsdk
Mar 25, 2026
Merged

[Node.js] Align Public APIs across SDKs#221
fpfp100 merged 17 commits intomainfrom
users/pefan/syncsdk

Conversation

@fpfp100
Copy link
Copy Markdown
Contributor

@fpfp100 fpfp100 commented Mar 19, 2026 •
edited
Loading

Summary

Aligns the Node.js observability SDK public APIs with the .NET and Python SDKs by restructuring scope method signatures to use typed request/details objects instead of long positional parameter lists.

Breaking Changes (@microsoft/agents-a365-observability)

  • InvokeAgentDetails renamed to InvokeAgentScopeDetails — now contains only scope-level config (endpoint). Agent identity (AgentDetails) is a separate parameter. sessionId moved to Request.
  • InvokeAgentScope.start(): New signature start(request, invokeScopeDetails, agentDetails, callerDetails?, spanDetails?). request is required. Tenant ID derived from agentDetails.tenantId. Caller info wrapped in CallerDetails.
  • InferenceScope.start(): New signature start(request, details, agentDetails, userDetails?, spanDetails?). request is required. Tenant ID derived from agentDetails.tenantId.
  • ExecuteToolScope.start(): New signature start(request, details, agentDetails, userDetails?, spanDetails?). Same pattern as InferenceScope.
  • OutputScope.start(): New signature start(request, agentDetails, userDetails?, spanDetails?). Same pattern.
  • AgentRequest renamed to Request — unified across all scopes. Removed InferenceRequest, ToolRequest, OutputRequest. Removed executionType field.
  • CallerDetails renamed to UserDetails — represents the human caller identity.
  • InvokeAgentCallerDetails renamed to CallerDetails — composite caller with userDetails and callerAgentDetails.
  • TenantDetails removed — tenantId absorbed directly into AgentDetails.
  • tenantDetails parameter removed from all scope start() methods. Tenant ID now required on AgentDetails.tenantId.
  • injectTraceContext() renamed to injectContextToHeaders().
  • extractTraceContext() renamed to extractContextFromHeaders().
  • setStartTime() removed — use SpanDetails.startTime on construction instead.
  • Caller derivation from agent details removed — UserDetails is always the human caller, not derived from callerAgentDetails.

Added

  • SpanDetails — groups parentContext, startTime, endTime, spanKind for scope construction.
  • CallerDetails — groups userDetails and callerAgentDetails for A2A scenarios.
  • Request — unified request context with conversationId, channel, content, sessionId.
  • OpenTelemetryScope.recordCancellation() — records cancellation with error.type = 'TaskCanceledException'.
  • OpenTelemetryConstants.ERROR_TYPE_CANCELLED constant.

🤖 Generated with Claude Code

@jsl517
feat: align InvokeAgentDetails with .NET/Python SDKs
ff63646 
BREAKING CHANGE: InvokeAgentDetails uses composition (details: AgentDetails)
instead of inheritance (extends AgentDetails).

- InvokeAgentScope.start() adds request and conversationId as separate params
- Removed providerName and agentBlueprintId from InvokeAgentDetails
- Added OpenTelemetryScope.setStartTime() and recordCancellation()
- Added OpenTelemetryConstants.ERROR_TYPE_CANCELLED constant
@fpfp100 fpfp100 requested review from a team as code owners March 19, 2026 01:26
Copilot AI review requested due to automatic review settings March 19, 2026 01:26
Copilot AI reviewed Mar 19, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Aligns the Node.js observability SDK’s InvokeAgentDetails and InvokeAgentScope.start() API shape/signature with the .NET and Python SDKs, while adding a couple of core scope utilities for timing and cancellation telemetry.

Changes:

  • Refactors InvokeAgentDetails from inheritance to composition ({ details: AgentDetails }) and updates InvokeAgentScope.start() signature to accept request and conversationId explicitly.
  • Adds OpenTelemetryScope.setStartTime() and OpenTelemetryScope.recordCancellation(), plus a new cancellation error-type constant.
  • Updates hosting utilities and test suites to the new API shapes/signatures.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
tests/observability/extension/hosting/scope-utils.test.ts Updates hosting utility tests for composed InvokeAgentDetails and new InvokeAgentScope.start() signature.
tests/observability/core/trace-context-propagation.test.ts Updates trace-context propagation tests to match the new start() parameter order.
tests/observability/core/scopes.test.ts Updates InvokeAgentScope tests for composed details; adds tests for conversationId precedence, request.channel tags, setStartTime, and recordCancellation.
tests/observability/core/parent-span-ref.test.ts Updates parent-span reference tests for composed details and new start() signature.
packages/agents-a365-observability/src/tracing/scopes/OpenTelemetryScope.ts Adds setStartTime() and recordCancellation(); adjusts duration logging; changes setTagMaybe visibility.
packages/agents-a365-observability/src/tracing/scopes/InvokeAgentScope.ts Implements new start() signature, derives channel tags from request.channel, and uses composed agent identity.
packages/agents-a365-observability/src/tracing/contracts.ts Updates InvokeAgentDetails to composition model and removes legacy header.
packages/agents-a365-observability/src/tracing/context/trace-context-propagation.ts Updates docs/examples for new InvokeAgentScope.start() signature.
packages/agents-a365-observability/src/tracing/constants.ts Adds OpenTelemetryConstants.ERROR_TYPE_CANCELLED.
packages/agents-a365-observability-hosting/src/utils/ScopeUtils.ts Adapts hosting scope population to build/pass request separately and merge identity into details.details.
CHANGELOG.md Documents breaking changes and new APIs introduced by this alignment work.

You can also share your feedback on Copilot code review. Take the survey.

@fpfp100 fpfp100 changed the title feat: align InvokeAgentDetails with .NET/Python SDKs Align [Node.js] public APIs across SDKs (Part 1): InvokeAgentScope Mar 19, 2026
@fpfp100 fpfp100 changed the title Align [Node.js] public APIs across SDKs (Part 1): InvokeAgentScope [Node.js] Public APIs across SDKs (Part 1) Mar 19, 2026
@fpfp100 fpfp100 changed the title [Node.js] Public APIs across SDKs (Part 1) [Node.js] Align Public APIs across SDKs (Part 1) Mar 19, 2026
nikhilNava
nikhilNava requested changes Mar 19, 2026
View reviewed changes
@jsl517 @claude
fix: address Copilot PR review comments and fix all test failures
c3eab6b 
- Revert setTagMaybe from public back to protected (Copilot comment #1)
- Only build request object when channel/conversationId data exists in
  ScopeUtils populate* methods, avoiding always-truthy empty channel
  objects (Copilot comment #2)
- Update all 5 failing test suites to match new scope API signatures:
  scopes.test.ts, output-scope.test.ts, parent-span-ref.test.ts,
  trace-context-propagation.test.ts, scope-utils.test.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@fpfp100 fpfp100 changed the title [Node.js] Align Public APIs across SDKs (Part 1) [Node.js] Align Public APIs across SDKs Mar 20, 2026
@jsl517 @claude
feat: add source files for scope API alignment
b0d099d 
Include all modified source files that were missing from the previous
commit: new scope signatures, contracts, exports, CHANGELOG, and
hosting middleware updates.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 20, 2026 02:40
Copilot AI reviewed Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Aligns the Node.js observability SDK public APIs with the .NET/Python SDKs by replacing long positional scope start() signatures with typed request/details objects, and consolidating span options into a single SpanDetails object.

Changes:

  • Refactors scope construction APIs (InvokeAgentScope, InferenceScope, ExecuteToolScope, OutputScope) to use request/details objects and derive tenant ID from AgentDetails.tenantId.
  • Renames W3C trace-context helpers to injectContextToHeaders / extractContextFromHeaders and updates exports + tests accordingly.
  • Adds SpanDetails, InvokeAgentCallerDetails, request context types, recordCancellation(), and ObservabilityBuilder.withServiceNamespace(); updates hosting utilities and test suite.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
tests/observability/extension/hosting/scope-utils.test.ts Updates hosting ScopeUtils tests for new details/request object shapes and updated error messages.
tests/observability/core/trace-context-propagation.test.ts Updates tests to use renamed context propagation helpers and new InvokeAgentScope.start() signature.
tests/observability/core/scopes.test.ts Updates scope tests for new signatures; adds coverage for conversationId/channel tagging and cancellation recording.
tests/observability/core/parent-span-ref.test.ts Updates parent-span tests for new SpanDetails.parentContext parameter pattern.
tests/observability/core/output-scope.test.ts Updates OutputScope tests for new request/SpanDetails-based constructor signature.
packages/agents-a365-observability/src/tracing/scopes/OutputScope.ts Switches OutputScope start signature to (request, response, agentDetails, ...) and derives tenantId from agentDetails.
packages/agents-a365-observability/src/tracing/scopes/OpenTelemetryScope.ts Updates docs for renamed extract helper; adds recordCancellation(); tweaks end-span logging.
packages/agents-a365-observability/src/tracing/scopes/InvokeAgentScope.ts Refactors InvokeAgentScope to composition-based InvokeAgentDetails.details and new caller/span option objects.
packages/agents-a365-observability/src/tracing/scopes/InferenceScope.ts Refactors InferenceScope to accept InferenceRequest + SpanDetails and derives tenantId from agentDetails.
packages/agents-a365-observability/src/tracing/scopes/ExecuteToolScope.ts Refactors ExecuteToolScope to accept ToolRequest + SpanDetails and derives tenantId from agentDetails.
packages/agents-a365-observability/src/tracing/contracts.ts Introduces request context interfaces, InvokeAgentCallerDetails, and SpanDetails; changes InvokeAgentDetails to composition.
packages/agents-a365-observability/src/tracing/context/trace-context-propagation.ts Renames inject/extract helpers; updates examples and runWithExtractedTraceContext() implementation.
packages/agents-a365-observability/src/tracing/constants.ts Adds ERROR_TYPE_CANCELLED constant value.
packages/agents-a365-observability/src/index.ts Re-exports renamed propagation helpers and newly added contract types.
packages/agents-a365-observability/src/ObservabilityBuilder.ts Adds withServiceNamespace() and emits service.namespace resource attribute when configured.
packages/agents-a365-observability-hosting/src/utils/ScopeUtils.ts Updates TurnContext-derived scope creation to build typed request objects and pass SpanDetails.
packages/agents-a365-observability-hosting/src/middleware/OutputLoggingMiddleware.ts Updates OutputLoggingMiddleware to pass OutputRequest + SpanDetails into OutputScope.
CHANGELOG.md Documents breaking API changes, additions, and renamed APIs.

juliomenendez
juliomenendez requested changes Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown

@juliomenendez juliomenendez left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are several argument changes in this PR. Can we review how to make them backwards compatible to avoid breaking existing integrations?

@fpfp100
Copy link
Copy Markdown
Contributor Author

fpfp100 commented Mar 20, 2026

There are several argument changes in this PR. Can we review how to make them backwards compatible to avoid breaking existing integrations?

Currently in preview phase. Discussed offline about the breaking changes. We will notify developers about the changes.

nikhilNava
nikhilNava requested changes Mar 20, 2026
View reviewed changes
nikhilNava
nikhilNava requested changes Mar 20, 2026
View reviewed changes
nikhilNava
nikhilNava requested changes Mar 20, 2026
View reviewed changes
jsl517 and others added 2 commits March 20, 2026 12:39
@jsl517 @claude
refactor: address PR review — rename types and unify Request interface
b14fe0a 
- Rename AgentRequest → Request, use across all scopes (remove
  InferenceRequest, ToolRequest, OutputRequest)
- Remove executionType from Request interface
- Rename CallerDetails → UserDetails (human caller)
- Rename InvokeAgentCallerDetails → CallerDetails (composite caller)
  with userDetails property instead of callerDetails
- InvokeAgentScope.start: request param is now required (not undefined)
- Remove caller derivation from agent details — caller is always human
- Fix stale JSDoc on populateInvokeAgentScopeFromTurnContext
- Update all tests for new type names

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@jsl517 @claude
docs: update CHANGELOG and design doc for type renames
fe81431 
- CHANGELOG: fix all stale type references (InvokeAgentCallerDetails →
  CallerDetails, InferenceRequest/ToolRequest/OutputRequest → Request,
  callerDetails → userDetails, AgentRequest → Request)
- design.md: update code examples to use new scope signatures
- design.md: fix InvokeAgentDetails to composition model
- ScopeUtils: fix stale comment on request building

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 20, 2026 20:23
Copilot AI reviewed Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

@jsl517 @claude
refactor: rename callerInfo → callerDetails on InvokeAgentScope
3b9bb82 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 20, 2026 21:19
@jsl517 @claude
refactor: make request required on all scopes, rename callerInfo
8a03a7b 
- Make request: Request required (not | undefined) on InferenceScope,
  ExecuteToolScope, and OutputScope to match InvokeAgentScope
- Rename callerInfo → callerDetails on InvokeAgentScope
- Fix JSDoc example in trace-context-propagation.ts
- Update ScopeUtils to always build Request objects
- Update all tests to pass {} instead of undefined for request

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

@jsl517 @claude
refactor: make request optional on Inference/ExecuteTool/OutputScope
c9b838e 
- Move request param after required params so it can be truly optional
  (details, agentDetails, request?, userDetails?, spanDetails?)
- Revert sessionId fallback — read only from invokeAgentDetails to
  match .NET/Python SDKs
- Update CHANGELOG and design docs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 20, 2026 23:00
@jsl517 @claude
fix: add tenantId check in OutputLoggingMiddleware, remove try/catch
0e04886 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Mar 20, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 5 comments.

@jsl517 @claude
fix: add defensive null check for InvokeAgentScope.details, add servi…
0bf75ea 
…ceNamespace test

- Guard against undefined invokeAgentDetails.details before accessing tenantId
- Add test for withServiceNamespace builder option (service.namespace resource attribute)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 23, 2026 20:05
Copilot AI reviewed Mar 23, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 2 comments.

Copilot AI review requested due to automatic review settings March 24, 2026 17:52
@fpfp100 fpfp100 force-pushed the users/pefan/syncsdk branch from db4052d to 20e8508 Compare March 24, 2026 17:52
Copilot AI reviewed Mar 24, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

nikhilNava
nikhilNava requested changes Mar 24, 2026
View reviewed changes
jsl517 and others added 2 commits March 24, 2026 12:46
@jsl517
refactor: split InvokeAgentDetails into InvokeAgentScopeDetails + Age…
d91fe81 
…ntDetails, move sessionId to Request
@jsl517 @claude
refactor: flatten TenantDetails into AgentDetails, rename InvokeAgent…
476311d 
…Details to InvokeAgentScopeDetails

Simplify contracts by removing single-field TenantDetails wrapper and
absorbing tenantId directly into AgentDetails. Update all scope
signatures, ScopeUtils helpers, docs, and tests accordingly.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings March 24, 2026 22:55
Copilot AI reviewed Mar 24, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated 8 comments.

jsl517 and others added 2 commits March 24, 2026 17:17
@jsl517
Merge remote-tracking branch 'origin/main' into users/pefan/syncsdk
3a7bdb6 
# Conflicts:
#	CHANGELOG.md
#	packages/agents-a365-observability-hosting/src/utils/ScopeUtils.ts
#	packages/agents-a365-observability/src/tracing/scopes/InvokeAgentScope.ts
#	packages/agents-a365-observability/src/tracing/scopes/OpenTelemetryScope.ts
#	tests/observability/core/scopes.test.ts
@jsl517 @claude
refactor: address PR review — remove tenantDetails from base scope, f…
55a29bc 
…ix stale docs

- Remove tenantDetails param from OpenTelemetryScope constructor; tenant ID
  now read directly from agentDetails.tenantId
- Remove redundant tenantDetails local variable from all 4 scope subclasses
- Remove duplicate operationName tag in InferenceScope (already set by base)
- Remove inconsistent request null-check from OutputScope (align with other scopes)
- Remove unused imports (ExecutionType, InvokeAgentScopeDetails, TenantDetails)
- Fix stale property names in design docs (callerId→userId, callerUpn→userEmail)
- Fix duplicate SourceMetadata changelog entry

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@fpfp100 fpfp100 merged commit a59eed6 into main Mar 25, 2026
7 checks passed
@fpfp100 fpfp100 deleted the users/pefan/syncsdk branch March 25, 2026 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@juliomenendez juliomenendez juliomenendez approved these changes

@nikhilNava nikhilNava nikhilNava approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@fpfp100 @juliomenendez @nikhilNava @jsl517